Introduction : Why should you in care in first place ?
Why you need to have a pre-build structure for any project, solo or with a team? Think about it: everything else around us has a well defined plan and a structure, so why not you also having a structure for your codebase?
Trust me, doing this upfront will save , hate from you teammates, Having multiple hands in signal a project can quickly turn the work into hell. But an agreed-upon structure guide everyone to the sweet spot where teamwork is actually an advantage, rather than a disadvantage.
there is no more descriptive quote as this one of Abraham Lincoln :
[!Quote] Give me six hours to chop down a tree and I will spend the first four sharpening the axe. Abraham Lincoln
I think this quote is pretty self-explanatory, but let's break down: sharping your axe upfront drastically accelerate your actual working progress. In this article I am going to give you exactly what you need to sharpen you axe. will get just enough to sharp you axe. We aren't just going to cover the what and the how; we are going to focus heavily on the why. Knowing the "why" gives you a much deeper understanding of the architecture, which will help you learn not just the concepts in this article, but every new concept in your coding journey.
what to expect and what I expect from you:
keep it simple. I assuming you already have about 1 or 2 years of coding experience. You should expect from me not a textbook detailing every single micro-concept, but rather just enough to help you grasp the basics(must to know), plus references to start you own deep dives.
Basic Standards(Rules, Rules, and more Rules)
Rules aren't bad as you think, they define a clear instructions to follow for a specific purpose, I agree that they are annoying some times, but for that purpose, we follow them. So what is you purpose? (save time and hate ;))
Project Structure
I ask ChatGPT, what is the optimal file tree for every project, here is the response:
A good project tree should make it obvious where code belongs, where tests belong, where configuration lives, and where generated files go. The exact names change between web, C/C++, Rust, Python, embedded systems, etc., but the underlying structure is almost always the same. Think about a project like this:
my-project/
│
├── src/ # Actual application/source code
├── tests/ # Tests
├── docs/ # Documentation
├── scripts/ # Build/deploy/helper scripts
├── config/ # Configuration, if you have a lot of it
├── assets/ # Images, fonts, static files, etc.
├── examples/ # Example usage, optional
├── tools/ # Internal development tools, optional
│
├── .gitignore
├── README.md
├── LICENSE
├── .env.example
│
└── build/package files
# Makefile, CMakeLists.txt, package.json,
# Cargo.toml, pyproject.toml, docker-compose.yml, etc.
The most important folder is usually
src/. Your actual program should be organized by responsibility, not by dumping everything into one folder.
He is right but, to be honest, it depends on the project, but the general idea is:
- src/ for logic code (source code)
- tests/ your basic tests for a quick verification of your main code(src/)
- docs for documentation, and will discus who you should document projects
- scripts/ for scripts may be you will need it on you cloud VM, one of the projects I worked on, we need to listen to an API every 20 min, so we decide to put it a external script, so the backend won't have to stop every thing and listen to that API.
- config/ a place where every settings your needs before it will be build, even during the production. Instead of filling .env with several variables and complicating it, use the config files(usually a JSON format).
- assets/ Assets, the every image, logos, static files. In shorter words, anything that you code base use, like an pre-build kit.
- examples/ In this directory, you put how the user use you application. One of the project that I worked on called miniRT, it's a ray tracing projects in C, so we (me and my partner) a directory, examples/ we put on it examples of file that you need to create before running the program, because it was strange put, to manipulate the output of the program.
- tools/
More directory you may need:
- media/
Version control: not just git
Commits: git commit -m "Done"
Project version
0.1v 1.1v ...
Pull request
Error handling: bug hunting
Logger: record it man
Logger of the most in important tools in bug hunting, Knowing what happened in your production even in the dev mode, frame you knowledge about the source problem on you code. If we are agree on this point, you should invest you time on learning about the logger of you environment,
Documentation: No One Was There When You Wrote It
APIs Documentation
Optimization: Good Engineers Write Fast Code, bro
Security: The Internet is Not a Safe Place
You secrets: manage well your .env
Dockerization:
Input Validation
Testing: Stop Testing in Production, Seriously
[!Quote] Program testing can be used to show the presence of bugs, but never to show their absence ! ** Edsger Djiktra**